/* vim: set sw=8 ts=8 sts=8 expandtab: */
#ifndef CMAID_LIST_H
#define CMAID_LIST_H

/**
 * @defgroup Cmaid_List The List Class
 * @ingroup Classes
 * @brief A List to store objects in Order
 *
 * The list provides an interface for a container to manage objects in an
 * ordered collection. Duplications are possible and the order is preserved
 * in the same way they were added to the container.
 *
 * It provides functions to append and prepend objects, to sort and reverse
 * the order. It is also possible to insert object, with an iterator defining
 * the position.
 */
/**
 * @brief Type definition of the List Class
 * @ingroup Cmaid_List
 */
typedef Cmaid_Container Cmaid_List;

/**
 * @defgroup Cmaid_List_Interface The List Interface
 * @ingroup Cmaid_List
 *
 * You only have to deal with the interface structure directly, if you are
 * going to write an implementation of the interface. Else you can safely
 * ignore this.
 *
 * @{
 */
/** Type definition for the @em append callback */
typedef void *(*Cmaid_List_Append_Cb)(Cmaid_List *t, const void *data);
/** Type definition for the @em prepend callback */
typedef void *(*Cmaid_List_Prepend_Cb)(Cmaid_List *t, const void *data);
/** Type definition for the @em remove @em first callback */
typedef void  (*Cmaid_List_First_Remove_Cb)(Cmaid_List *t);
/** Type definition for the @em remove @em last callback */
typedef void  (*Cmaid_List_Last_Remove_Cb)(Cmaid_List *t);
/** Type definition for the @em first callback */
typedef void *(*Cmaid_List_First_Cb)(Cmaid_List *t);
/** Type definition for the @em last callback */
typedef void *(*Cmaid_List_Last_Cb)(Cmaid_List *t);
/** Type definition for the @em insert @em before callback */
typedef void *(*Cmaid_List_Insert_Before_Cb)(Cmaid_List *t, const Cmaid_Iter *it, const void *data);
/** Type definition for the @em insert @em after callback */
typedef void *(*Cmaid_List_Inset_After_Cb)(Cmaid_List *t, const Cmaid_Iter *it, const void *data);
/** Type definition for the @em sort_with callback */
typedef void  (*Cmaid_List_Sort_With_Cb)(Cmaid_List *t, Cmaid_Value_Compare_Cb cmp);
/** Type definition for the @em reverse callback */
typedef void  (*Cmaid_List_Reverse_Cb)(Cmaid_List *t);

/** Type definition for the @em list interface */
typedef struct Cmaid_List_Interface Cmaid_List_Interface;

/**
 * @brief The List Interface structure
 * The list interface is inheriting from the container and thus must also
 * have interface functions for the container.
 */
struct Cmaid_List_Interface
{
        Cmaid_Container_Interface   container_if;
        Cmaid_List_Append_Cb        append;
        Cmaid_List_Prepend_Cb       prepend;
        Cmaid_List_First_Remove_Cb  first_remove;
        Cmaid_List_Last_Remove_Cb   last_remove;
        Cmaid_List_First_Cb         first;
        Cmaid_List_Last_Cb          last;
        Cmaid_List_Insert_Before_Cb insert_before;
        Cmaid_List_Inset_After_Cb   insert_after;
        Cmaid_List_Sort_With_Cb     sort_with;
        Cmaid_List_Reverse_Cb       reverse;
};
/**
 * @}
 */
/**
 * @addtogroup Cmaid_List
 * @{
 */
CMAID_INLINE void *cmaid_list_append(Cmaid_List *t, const void *data);
CMAID_INLINE void *cmaid_list_prepend(Cmaid_List *t, const void *data);
CMAID_INLINE void  cmaid_list_first_remove(Cmaid_List *t);
CMAID_INLINE void  cmaid_list_last_remove(Cmaid_List *t);
CMAID_INLINE void *cmaid_list_first(Cmaid_List *t);
CMAID_INLINE void *cmaid_list_last(Cmaid_List *t);
CMAID_INLINE void *cmaid_list_insert_before(Cmaid_List *t, Cmaid_Iter *iter,
                                                        const void *data);
CMAID_INLINE void *cmaid_list_insert_after(Cmaid_List *t, Cmaid_Iter *iter,
                                                        const void *data);
CMAID_INLINE void  cmaid_list_sort(Cmaid_List *t);
CMAID_INLINE void  cmaid_list_sort_with(Cmaid_List *t, Cmaid_Value_Compare_Cb cmp);
CMAID_INLINE void  cmaid_list_reverse(Cmaid_List *t);
/**
 * @}
 */
#include <cmaid_list_funcdef.h>

#endif
